feat: flip to the v3 information architecture#2702
Conversation
Relocate sections to match the v3 IA: - console pages fold into Account (/account/*), console index -> /account/console - collaboration folds under Account (/account/collaboration/*), organization_account renamed to organization - schedules and monitoring move under Actors > running (/actors/running/*) - schedule and monitoring images move alongside their pages Add the Account hub (/account) and the opinionated Get Started section (/get-started: locally, web-ide, build-with-ai, develop-ai-agents).
With routeBasePath moving to root, rewrite /platform/* references to /* across authored content, the OpenAPI source components (charge.yaml, Dataset.yaml, ActorDefinition.yaml, datasetParameters.yaml), and the custom React pages. Move-aware: links into relocated sections point at their new v3 paths (e.g. /account/*, /actors/running/*).
- docusaurus.config.js: routeBasePath 'platform' -> '/' - config.js: swap navbar.items to the v3 set (Get started, Actors, Storage, Proxy, Account, Integrations, Limits, Security | Academy, APIs, SDKs & CLI); move Open source from a nav dropdown to a footer column - sources/platform/sidebars.js: per-section autogenerated sidebars
Point DocItemContent's allowed paths and the SearchBar instance check at the eight v3 section roots instead of the single /platform tree.
The docs root is now the entry point (src/pages/index.tsx); the old /platform index page collided with slug: / after the routeBasePath flip.
Add an nginx block with a /platform/* -> /* catch-all plus structural pre-rules for relocated sections (console -> account, collaboration, schedules/monitoring -> actors/running, quick-start -> get-started, airtable console-integration soft-land, /platform root). console/store keeps its URL pending the open store-page decision. Stripping /platform/ from existing rule targets (double-hop cleanup) is left to a follow-up PR; those URLs still resolve via the catch-all.
TC-MO
added
documentation
|
🗑️ Preview for this PR was deleted. |
|
Important Action required — @TC-MO please coordinate this docs PR with the Python API client PR linked below. Because this PR modifies the OpenAPI specification, the generated models in A companion PR has been opened in
|
The Actors, Storage, Proxy, and Integrations hub pages kept their old single-sidebar positions and had no sidebar_label, so they showed the section name and (for Integrations) sorted mid-list. Add sidebar_label: Overview and sidebar_position: 0 to match Account and Get started.
The dedicated Open source footer column makes the Open source link in the Other column redundant.
Now that Get Started covers two journeys, give them structure: - move "Apify for AI agents" from Integrations into Get Started as the top-level "Agent onboarding" page (the consume-Apify path) - group the four build pages (Local development, Web IDE, Build with AI, Develop AI agents) under an expanded "Build" category (the build-on-Apify path); they keep their flat /get-started/* slugs The page moved out of Integrations, so redirect its live URL and update inbound links. The directory is named building/ because a bare "build" is gitignored (Docusaurus output dir).
The quick start pages duplicated the new Get Started build pages (same content, different URLs). Delete the tree and migrate its unique "Technology stack" intro into the Actor development overview, which also gives that section a proper opening now that quick start no longer leads it. Repoint inbound links to Get Started; old /platform quick-start URLs already redirect there via nginx.
The header-assertion smoke test used /platform/proxy/datacenter-proxy as its sample page; after the flip that 301s to /proxy/datacenter-proxy, so the trailing-slash, Content-Type, and .md-alternate assertions now target the v3 URL.
Dropping the /platform prefix shortened link cells in two tables, pushing their closing pipes out of alignment (markdownlint MD060). Re-pad to match.
Vale flagged them once the flip's link rewrite brought these files into the changed-file set.
The repo kept pre-/platform aliases like `^/proxy$ -> /platform/proxy` and `^/storage/dataset$ -> /platform/storage/dataset` from before the docs used a /platform prefix. The flip drops that prefix, so those source paths are now the canonical v3 URLs and serve directly. Combined with the new `/platform/* -> /*` catch-all they formed 301 loops (`/proxy -> /platform/proxy -> /proxy`), which broke the header-assertion smoke test (`/proxy/datacenter-proxy` no longer served its page). Remove the 19 aliases whose path now exists as a v3 route (one targeted an anchor: `/actors/running/input-and-output`). /monitoring and /schedules are kept - their pages moved under /actors/running, so they still redirect. Verified with a redirect-chain simulator: 0 loops and 0 gaps across all 347 literal redirect sources and the 165 production /platform URLs.
The smoke test in checkNavHeaders.mjs sampled hardcoded /platform/*.md pages; after the flip those 404 or live at the v3 path. Repoint them and drop /platform.md (the platform root landing is gone; its key combo is already covered by /academy, /api, /legal). In the v3 per-section sidebars a section landing (/actors, /storage, /integrations) is the first item and a sibling link, so it carries only `next` - no `previous` (nothing before it) and no `children` (its sub-pages are siblings, not nested). The `children` combo stays covered by /actors/running and /api/v2. Verified against locally generated headers.
TC-MO
requested review from
fnesveda,
honzajavorek,
janbuchar,
marcel-rbro and
szaganek
as code owners
|
@fnesveda @janbuchar FYI the only changes in the OpenAPI are link changes (removing /platform prefix) |
| { | ||
| label: 'APIs, SDKs & CLI', | ||
| type: 'dropdown', | ||
| to: `${absoluteUrl}/api/v2`, |
There was a problem hiding this comment.
With the the to property here, you imo won't be able to access the contents of the dropdown on touchscreen devices (tapping APIs, SDKs & CLI will navigate to /api/v2 immediately)
| label: 'APIs, SDKs & CLI', | ||
| type: 'dropdown', | ||
| to: `${absoluteUrl}/api/v2`, | ||
| activeBasePath: 'api', |
There was a problem hiding this comment.
The child links start with /cli, /sdk and /api. Perhaps activeBaseRegex (docs) can be of use?
| - Outcome-focused: #Productivity #Efficiency #Automation | ||
| - Broad professional: #BusinessGrowth #ProfessionalDevelopment | ||
| - Tool/platform: #NoCode #DataAnalysis #WebScraping | ||
| - Tool/: #NoCode #DataAnalysis #WebScraping |
There was a problem hiding this comment.
this might be find&replace collateral damage
janbuchar
left a comment
janbuchar
left a comment
There was a problem hiding this comment.
The OpenAPI changes are fine
- navbar: drop `to`/`target`/`rel` from the "APIs, SDKs & CLI" dropdown so tapping the label opens the menu on touchscreens instead of navigating straight to /api/v2 (children were unreachable on mobile) - navbar: switch activeBasePath:'api' to activeBaseRegex '^/(api|sdk|cli)/' so the item highlights across all three child destinations - restore "Tool/platform" in the LinkedIn prompt template (the /platform link rewrite stripped it to "Tool/")
Get Started pages are parallel entry points (agent onboarding plus the Build group's alternative ways to start), not a sequential course. The sidebar pagination threaded them as if they were steps, so disable it via pagination_next/pagination_prev: null on each page.
# Conflicts: # sources/platform/actors/development/programming_interface/environment_variables.md
| :::info Pass platform usage costs to users | ||
|
|
||
| Optionally, you can [pass costs associated with the platform usage](../../../platform/actors/publishing/monetize/pay-per-event#pass-platform-usage-to-users) to the users. | ||
| Optionally, you can [pass costs associated with the platform usage](../../../actors/publishing/monetize/pay-per-event#pass-platform-usage-to-users) to the users. |
There was a problem hiding this comment.
Might as well
| Optionally, you can [pass costs associated with the platform usage](../../../actors/publishing/monetize/pay-per-event#pass-platform-usage-to-users) to the users. | |
| Optionally, you can [pass costs associated with the platform usage](/actors/publishing/monetize/pay-per-event#platform-usage-costs) to the users. |
There was a problem hiding this comment.
Also, the anchor is wrong, should be #platform-usage-costs
| to="/integrations/claude-desktop" | ||
| imageUrl="/img/integrations/anthropic.svg" | ||
| imageUrlDarkTheme="/img/integrations/anthropic-white.svg" |
There was a problem hiding this comment.
Probably another autoreplace artifact: all icons (and maybe some images) are not displayed, as their path still contains the /platform/ part.
|
In |
- restore /img/platform/integrations/ icon paths across 7 integration index pages (the /platform link rewrite wrongly stripped them, 404ing 56 icons) - fix the platform-usage-costs anchor in how_actor_monetization_works.md (was the stale #pass-platform-usage-to-users)
|
I tried creating an overview for Build, but each time it ended up either really scarce and low-value, or cannibalizing the broader overview and making both weaker in the process. I'd ship it as is for now and keep working on it post-flip. |
|
@TC-MO, I don't think we should ship it like that. Having collapsible elements that sometimes have content and sometimes don't? It's confusing, we need consistency. What's wrong with the existing overview? (Okay, probably a lot. But still usable.) |
marcel-rbro
left a comment
marcel-rbro
left a comment
There was a problem hiding this comment.
Good with me once all pending comments are resolved 👍
|
@szaganek I agree that consistency would be preferable. The old overview was redistributed into other parts of the docs: Technology stack is now in Actor development, where I think it makes more sense, and the first-step/build-path routing is covered by the general Get started overview plus the Build sidebar group. Anything I tried to recreate as a Build overview either cannibalized the general Get started page or became a thin routing page with little standalone value. I’d rather avoid adding that just for sidebar consistency unless we can make it meaningfully useful. I’m happy to brainstorm a better Build overview, but I’d prefer not to block the IA flip on a page that we don’t yet know how to make meaningfully useful. |
|
What is your Claude even rambling about :D |
/platform/storage/usage merged into the /storage hub, so after the flip's redirects the old link would 404 at /storage/usage. Point it straight at /storage#data-retention.
|
Important Action required — @TC-MO please coordinate this docs PR with the Python API client PR linked below. Because this PR modifies the OpenAPI specification, the generated models in The companion
|
Move the build-path routing out of the Get started overview into a new /get-started/build landing (intro + card grid), so the Build sidebar category is clickable and the routing isn't duplicated across both pages.
- Updates the auto-generated Pydantic models and TypedDicts based on the proposed OpenAPI specification changes. - Based on apify-docs PR [#2702](apify/apify-docs#2702).
7 participants
Switches the docs from the
/platform/*URL structure to the v3 information architecture: topic-first sections at the site root,routeBasePathdropped to/, and 301 redirects covering old URLs.Review by commit
The flip is categorized by concern; commits 1-2 are mechanical (bulk moves and link rewrites) and can be skimmed, the judgment lives in 3-6. Commits 7-10 are refinements from reviewing the live preview.
DocItemContentallowed paths and theSearchBarinstance check.Verification
Build green at the tip, 0 broken links. The broken-anchor warnings are pre-existing and non-blocking (
onBrokenAnchors: 'warn').nginx double-hop cleanup - stripping
/platform/from the ~135 existing rule targets is a separate post-flip PR; those URLs still resolve via the catch-all in the meantime, just with an extra hop.